Framework

Contains information about a player's current game state.

Characters are a fundamental object type in Lilia. They are distinct from players, where players are the representation of a person's existence in the server that owns a character, and their character is their currently selected persona. All the characters that a player owns will be loaded into memory once they connect to the server. Characters are saved during a regular interval (lia.config.CharacterDataSaveInterval), and during specific events (e.g., when the owning player switches away from one character to another).

They contain all information that is not persistent with the player; names, descriptions, model, currency, etc. For the most part, you'll want to keep all information stored on the character since it will probably be different or change if the player switches to another character. An easy way to do this is to use lia.char.registerVar to easily create accessor functions for variables that automatically save to the character object.

Functions

characterMeta:__eq(other)

Compares this character with another character for equality based on their unique IDs.

Parameters

  • other Character

    The other character to compare against.

Returns

  • Boolean

    true if both characters have the same ID; otherwise, false.

Example Usage

local char1 = lia.char.loaded[1]
local char2 = lia.char.loaded[2]
print(char1 == char2)
Output: false

characterMeta:__tostring()

Provides a human-readable string representation of the character.

Returns

  • String

    A string in the format "character[ID]", where ID is the character's unique identifier.

Example Usage

print(lia.char.loaded[1])
Output: "character[1]"

characterMeta:ban(time)

Bans the character, preventing it from being used for a specified duration or permanently if no duration is provided. This action also forces the player out of the character.

Parameters

  • time Float

    The duration of the ban in seconds. If omitted or nil, the ban is permanent.

Example Usage

character:ban(3600) -- Bans the character for 1 hour
character:ban() -- Permanently bans the character

characterMeta:delete()

Removes the character from the database and memory, effectively deleting it permanently.

Example Usage

character:delete()

characterMeta:destroy()

Destroys the character instance, removing it from memory and ensuring it is no longer tracked by the server. This does not delete the character from the database.

Example Usage

character:destroy()

characterMeta:getFlags()

Retrieves all flags associated with this character.

Returns

  • String

    A concatenated string of all flags the character possesses. Each character in the string represents an individual flag.

Example Usage

local flags = character:getFlags()
for i = 1, #flags do
    local flag = flags:sub(i, i)
    print("Flag:", flag)
end

characterMeta:getID()

Retrieves the unique database ID of this character.

Returns

  • Integer

    The unique identifier of the character.

Example Usage

local charID = character:getID()
print(charID)
Output: 1

characterMeta:getItemWeapon()

Retrieves the currently equipped weapon of the character along with its corresponding inventory item.

Returns

  • Entity or false

    The equipped weapon entity if a weapon is equipped; otherwise, false.

  • Item or false

    The corresponding item from the character's inventory if found; otherwise, false.

Example Usage

local weapon, item = character:getItemWeapon()
if weapon then
    print("Equipped weapon:", weapon:GetClass())
else
    print("No weapon equipped.")
end

characterMeta:getPlayer()

Obtains the player object that currently owns this character.

Returns

  • The

    player who owns this character, or nil if no valid player is found.

Example Usage

local owner = character:getPlayer()
if owner then
    print("Character is owned by:", owner:Nick())
end

characterMeta:giveFlags(flags)

Adds one or more flags to the character's existing set of accessible flags without removing existing ones.

Parameters

  • flags String

    A string containing one or more flags to add.

Example Usage

character:giveFlags("pet")
Adds 'p', 'e', and 't' flags to the character

characterMeta:giveMoney(amount, takingMoney)

Adds or subtracts money from the character's wallet. This function handles both giving and taking money based on the takingMoney parameter. When adding money, it respects the maximum money limit and handles overflow by dropping excess money on the ground.

Parameters

  • amount Float

    The amount of money to modify. Positive to add, negative to subtract.

  • takingMoney Boolean

    Optional. If true, the operation is treated as taking money; otherwise, adding money.

Returns

  • Boolean

    Always returns true to indicate the operation was processed.

Example Usage

character:giveMoney(500) -- Adds 500 to the character's wallet
character:giveMoney(-200, true) -- Takes 200 from the character's wallet

characterMeta:hasFlags(flags)

Determines if the character has one or more specified flags.

Parameters

  • flags String

    A string containing one or more flags to check.

Returns

  • Boolean

    true if the character has at least one of the specified flags; otherwise, false.

Example Usage

if character:hasFlags("admin") then
    print("Character has admin privileges.")
end

characterMeta:hasMoney(amount)

Checks whether the character possesses at least a specified amount of in-game currency.

Parameters

  • amount Float

    The minimum amount of currency to check for. Must be a non-negative number.

Returns

  • Boolean

    true if the character's current money is equal to or exceeds the specified amount; otherwise, false.

Example Usage

local hasEnoughMoney = character:hasMoney(100)
if hasEnoughMoney then
    print("Character has sufficient funds.")
else
    print("Character lacks sufficient funds.")
end

characterMeta:kick()

Forces the player to exit their current character and redirects them to the character selection menu. This is typically used when a character is banned or deleted.

Example Usage

character:kick()

characterMeta:save(callback)

Persists the character's current state and data to the database.

Parameters

  • callback Function

    An optional callback function to execute after the save operation completes successfully.

Example Usage

character:save(function()
    print("Character saved successfully!")
end)

characterMeta:setFlags(flags)

Sets the complete set of flags accessible by this character, replacing any existing flags. Note: This method overwrites all existing flags and does not append to them.

Parameters

  • flags String

    A string containing one or more flags to assign to the character.

Example Usage

character:setFlags("petr")
This sets the character's flags to 'p', 'e', 't', 'r'

characterMeta:setup(noNetworking)
Internal

This is an internal function! You are able to use it, but you risk unintended side effects if used incorrectly.

Configures the character's appearance and synchronizes this information with the owning player. This includes setting the player's model, faction, body groups, and skin. Optionally, it can prevent networking to other clients.

Parameters

  • noNetworking Boolean

    Optional. If set to true, the character's information will not be synchronized with other players.

Example Usage

character:setup()

characterMeta:sync(receiver)
Internal

This is an internal function! You are able to use it, but you risk unintended side effects if used incorrectly.

Synchronizes the character's data with clients, making them aware of the character's current state. This method handles different synchronization scenarios: - If receiver is nil, the character's data is synced to all connected players. - If receiver is the owner of the character, full character data is sent. - If receiver is not the owner, only limited data is sent to prevent unauthorized access.

Parameters

  • receiver Player

    The specific player to send the character data to. If nil, data is sent to all players.

characterMeta:takeFlags(flags)

Removes one or more flags from the character's set of accessible flags.

Parameters

  • flags String

    A string containing one or more flags to remove.

Example Usage

For a character with "pet" flags
character:takeFlags("p")
The character now only has 'e' and 't' flags

characterMeta:takeMoney(amount)

Specifically removes money from the character's wallet. This function ensures that only positive values are used to subtract from the wallet.

Parameters

  • amount Float

    The amount of money to remove. Must be a positive number.

Returns

  • Boolean

    Always returns true to indicate the operation was processed.

Example Usage

character:takeMoney(100) -- Removes 100 from the character's wallet